JBoss.orgCommunity Documentation
The Mobicents SIP Presence Service is built on top of Mobicents JAIN SLEE. JAIN SLEE applications can be deployed and run in the same JVM as the servers. There are also XDM and SIP Presence client enablers that can be integrated into these JAIN SLEE applications, allowing for easy interaction with the platform servers.
The Mobicents SIP Presence exposes a JAIN SLEE enabler for applications that can interact as clients of the XDM Server. The enabler is an extension of the XDM Client Enabler which exists in Mobicents JAIN SLEE. The only difference is that upon requests targeting the local and integrated XDM Server, the enabler does not uses XCAP or SIP network protocols, thus providing better performance and less overhead to network communications.
Please refer to the bundled JAIN SLEE documentation for complete details about how to integrate the enabler. The only difference to note in this document is the configuration of the client JAIN SLEE application SBB's XML Descriptor. The extended XDM Client Enabler SBB has the following ID:
<sbb-name>InternalXDMClientControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
This means that when integrating the enabler, the Parent's (the client application) Sbb XML Descriptor will refer to the ID above, instead of:
<sbb-name>XDMClientChildSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications that want to interact as clients of a SIP Event Publication Server. The enabler does not use SIP network protocols, thus providing better performance and less overhead to network communications.
The Enabler is an SBB that can be used in child relations, with a simple synchronous interface.
This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.
A Service's Sbb will define the Enabler's Sbb as a child. To achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.
The Service's Sbb will be referred to as the Parent Sbb in the following sections.
The Mobicents SIP Event Publication Client Enabler Sbb does not provides asynchronous callbacks to the Parent's Sbb at the moment, that is, all operations invoked in the child sbb will return a response. Thus the Parent does not needs to implement a specific interface.
The Enabler's Sbb is a Child Sbb, and JAIN SLEE 1.1 Child Relations requires an abstract method in the Sbb Abstract Class, to retrieve the javax.slee.ChildRelation
object, which is used to create or access specific Child Sbbs. This method should be:
public abstract ChildRelation getSIPEventPublicationClientChildRelation();
The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.
A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:
<sbb-ref>
<sbb-name>PublicationControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
<sbb-alias>sipEventPublicationClientChildSbb</sbb-alias>
</sbb-ref>
The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:
<get-child-relation-method>
<sbb-alias-ref>sipEventPublicationClientChildSbb</sbb-alias-ref>
<get-child-relation-method-name>getSIPEventPublicationClientChildRelation</get-child-relation-method-name>
<default-priority>0</default-priority>
</get-child-relation-method>
In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.
The Mobicents SIP Event Publication Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.publication.PublicationClientControlSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sipevent.server.publication.PublicationClientControl
interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:
package org.mobicents.slee.sipevent.server.publication;
public interface PublicationClientControl {
public Result newPublication(String entity, String eventPackage,
String document, String contentType, String contentSubType,
int expires);
public Result refreshPublication(String entity, String eventPackage,
String eTag, int expires);
public Result modifyPublication(String entity, String eventPackage,
String eTag, String document, String contentType,
String contentSubType, int expires);
public int removePublication(String entity, String eventPackage, String eTag);
}
newPublication(String, String, String, String, String, int)
method:Requests a new publication, for the specified Entity and SIP Event Package.
refreshPublication(String, String, String, int)
method:Requests a publication refresh, for the specified Entity, SIP Event Package and ETag.
modifyPublication(String, String, String, String, String, String, int)
method:Requests a publication modification, for the specified Entity, SIP Event Package and ETag.
removePublicationOk(String, String, String)
method:Requests a publication removal, for the specified Entity, SIP Event Package and ETag.
The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:
public PublicationClientControl getPresenceClientChildSbb() {
final ChildRelation childRelation = getSIPEventPublicationClientChildRelation();
if (childRelation.isEmpty()) {
try {
// creates new instance
return (PublicationClientControl) childRelation.create();
} catch (Exception e) {
tracer.severe("Failed to create child sbb", e);
return null;
}
}
else {
// reuse the existent one
return (PublicationClientControl) childRelation.iterator().next();
}
}
The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Subscription Server, such as a PS or RLS. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.
The Enabler is an SBB, which can be used in child relations, with a simple asynchronous interface.
This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.
In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.
The Service's Sbb will be referred as the Parent Sbb in the following sections.
The Mobicents SIP Event Subscription Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.
The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParentSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParent
interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:
package org.mobicents.slee.sipevent.server.subscription;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface SubscriptionClientControlParent {
public void subscribeOk(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires,
int responseCode);
public void resubscribeOk(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires);
public void unsubscribeOk(String subscriber, String notifier,
String eventPackage, String subscriptionId);
public void subscribeError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void resubscribeError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void unsubscribeError(String subscriber, String notifier,
String eventPackage, String subscriptionId, int error);
public void notifyEvent(String subscriber, String notifier,
String eventPackage, String subscriptionId,
Subscription.Event terminationReason, Subscription.Status status,
String content, String contentType, String contentSubtype);
}
subscribeOk(String, String, String, String, int, int)
method:Callback from the Enabler indicating that the new subscription request succeed.
resubscribeOk(String, String, String, String, int)
method:Callback from the Enabler indicating that the refresh subscription request succeed.
unsubscribeOk(String, String, String, String)
method:Callback from the Enabler indicating that the remove subscription request succeed.
subscribeError(String, String, String, String, int)
method:Callback from the Enabler indicating that the new subscription request failed.
resubscribeError(String, String, String, String, int)
method:Callback from the Enabler indicating that the refresh subscription request failed.
unsubscribeError(String, String, String, String, int)
method:Callback from the Enabler indicating that the remove subscription request failed.
notifyEvent(String, String, String, String, Subscription.Event, Subscription.Status, String, String, String)
method:Callback from the Enabler notifying an event related with notifier state change.
The Parent Sbb Abstract Class must implement the callbacks on it's SbbLocalObject, that is, must implement the org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParent
interface discussed in last section.
The Enabler's Sbb is a Child Sbb, and JAIN SLEE 1.1 Child Relations requires an abstract method in the Sbb Abstract Class, to retrieve the javax.slee.ChildRelation
object, which is used to create or access specific Child Sbbs. This method should be:
public abstract ChildRelation getSIPEventSubscriptionClientChildRelation();
The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.
A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:
<sbb-ref>
<sbb-name>SubscriptionControlSbb</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
<sbb-alias>sipEventSubscriptionClientChildSbb</sbb-alias>
</sbb-ref>
The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:
<get-child-relation-method>
<sbb-alias-ref>sipEventSubscriptionClientChildSbb</sbb-alias-ref>
<get-child-relation-method-name>getSIPEventSubscriptionClientChildRelation</get-child-relation-method-name>
<default-priority>0</default-priority>
</get-child-relation-method>
Finally, after the sbb-abstract-class
element the Parent's SbbLocalObject interface name is defined:
<sbb-local-interface>
<sbb-local-interface-name>...</sbb-local-interface-name>
</sbb-local-interface>
In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.
The Mobicents SIP Event Subscription Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject
, which extends the javax.slee.SbbLocalObject
and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject
interfaces, the latter declares the methods which can be used to interact with the SIP Event Subscription Server:
package org.mobicents.slee.sipevent.server.subscription;
public interface SubscriptionClientControl {
public void setParentSbb(
SubscriptionClientControlParentSbbLocalObject sbbLocalObject);
public void subscribe(String subscriber, String subscriberdisplayName,
String notifier, String eventPackage, String subscriptionId,
int expires, String content, String contentType,
String contentSubtype);
public void resubscribe(String subscriber, String notifier,
String eventPackage, String subscriptionId, int expires);
public void unsubscribe(String subscriber, String notifier,
String eventPackage, String subscriptionId);
}
setParentSbb(SubscriptionClientControlParentSbbLocalObject)
method:Passes the Parent's SbbLocalObject, which will be used by the Child Sbb to provide async results. If not invoked after the child creation the Enabler won't be able to callback the Parent Sbb.
subscribe(String, String, String, String, String, int, String, String, String)
method:Requests a new subscription.
resubscribe(String, String, String, String, int)
method:Requests a subscription refresh.
unsubscribe(String, String, String, String)
method:Requests a subscription removal.
The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:
public SubscriptionClientControl getSIPEventSubscriptionClientChildSbb() {
final ChildRelation childRelation = getSIPEventSubscriptionClientChildRelation();
if (childRelation.isEmpty()) {
try {
// creates new instance
SubscriptionClientControl sbb = (SubscriptionClientControl) childRelation.create();
// passes the parent sbb local object to the child
sbb.setParentSbb((SubscriptionClientControlParentSbbLocalObject) sbbContext.getSbbLocalObject());
return sbb;
} catch (Exception e) {
tracer.severe("Failed to create child sbb", e);
return null;
}
}
else {
// reuse the existent one
return (SubscriptionClientControl) childRelation.iterator().next();
}
}